---
description: Metadata best practices
keywords:
  - hasura
  - docs
  - best practices
sidebar_label: Metadata Best Practices
sidebar_position: 12
---

# Metadata Best Practices

## Introduction

Proper Metadata management ensures the Hasura GraphQL Engine operates appropriately and as expected. You can use several
different patterns to manage Metadata successfully. However, the below do's, and don'ts have been gathered through
real-world practices, user experiences, and challenges when managing enterprise-scale Hasura ecosystems.

### Recommended patterns

- Always use custom environment variables instead of hardcoded values whenever possible.  These environment variables can then be reused in the other environments (e.g., staging or production) while containing a reference to the environment-specific values. This is necessary for a seamless CI/CD implementation.

  For example, the metadata contains a reference to `my_database_conn_string` but the environment variable for the development environment refers to the development database while the production environment refers to the production database.  Hasura will appropriately substitute these values when using the connection strings.

  - The environment variable can be any plain-text value, such as `my_remote_schema_url`, but should not start `HASURA_...` in order to easily identify the environment variable as used natively by Hasura or created by the user.

  - The Console allows for configuration of many things, such as data sources, by specifying connection via environment variable.  Select this option and enter the environment variable you declared in your deployment.

  - Some features, such as Remote Schemas, do not explicitly have a configuration for this in the Console.  In these situations, templatize the environment variable by wrapping it in double curly brackets.  e.g. `{{my_remote_schema_url}}`

- Use the [Hasura CLI](/hasura-cli/overview.mdx) to manage and export Metadata.

  - The CLI exports [YAML files](/migrations-metadata-seeds/manage-metadata.mdx) which is much more source-control
    friendly than JSON (exported by the Console and API).
  - Using the [Hasura CLI Console](/hasura-cli/commands/hasura_console.mdx) will capture all Metadata changes in the
    local file system as the changes are made.

- Use the [Hasura CLI Console](/hasura-cli/commands/hasura_console.mdx) as your development Console.

  - [Disable the Hasura GraphQL default Console](/deployment/production-checklist.mdx#disable-console).
  - Changes via the CLI Console will be detected and will update the local file system.

- Leverage a version control solution such as GitHub or GitLab as the source of truth for the Metadata configuration.
  - Local files updated by the CLI Console are then committed to the source control solution.
- We recommend retaining the CLI-exported file structure for ease of use.

- Automate deployments using tools such as GitHub Actions, Jenkins, or the
  [CLI-migrations image](/migrations-metadata-seeds/auto-apply-migrations.mdx).

:::info Note

Hasura Cloud users can leverage the [GitHub integration](/cloud-ci-cd/github-integration.mdx) to automate
deployments.

:::

- Ensure good regression testing is implemented as part of the deployment workflow.
  - [graphqurl](https://github.com/hasura/graphqurl) is a simple tool that can be used to execute GraphQL queries and
    compare the results to known values.

Use the Enterprise Edition for local development if the other Hasura tiers are Enterprise Edition. Using this image is
required to allow for the configuration of Hasura Enterprise features (i.e., read-replicas), so the Hasura CLI will
include the configurations in the exported Metadata.

### Patterns to avoid

- Don't use the Console or API to export Metadata.

  - The Console and API export JSON files that are not as source-control friendly as YAML (exported by the CLI).

- Don't use the Hasura GraphQL default Console as your development Console.

  - Changes made via the Hasura GraphQL default Console will not capture Metadata changes and can easily cause systems
    to be out of sync.

- Don't rely on the local file system or the Hasura Metadata database as the source of truth for the Metadata
  configuration.

  - Local files can easily be unintentionally modified, corrupted, or lost.
  - You can unintentionally modify the Hasura Metadata database through misapplication of Metadata changes.
  - The Hasura Metadata database could be unintentionally lost if you accidentally delete the supporting database or
    persistent volume.

- Don't manually deploy. While this will work in practice, it will quickly grow beyond a reasonable level of effort as
  the system's complexity and frequency of deployments increase.

- Don't skip good regression testing as Metadata changes can easily change the fundamental way the Hasura GraphQL Engine
  operates. Queries you structure differently may return unexpected results. You could modify security policies such as
  RBAC permissions or allowed queries via Metadata changes that cause unexpected behavior.

- Don't apply Metadata generated from the Community Edition to an Enterprise Edition system that has Enterprise Edition
  features configured (e.g., read-replicas). Hasura stores these configurations in the Metadata, and the Community
  Edition cannot configure these features. The resulting exported Metadata will not contain these values, and this
  Metadata would overwrite the Enterprise Edition configurations if you applied it.
